Expose Management API rate limit info via a client callback - #774

Changes

Exposes Auth0's rate-limit information (x-ratelimit-limit / -remaining / -reset) from every Management API response, so callers can monitor how close they are to the limit (the ask in #606). It's delivered via an opt-in callback rather than a changed return value — see the note below on why.

• Auth0::Internal::Http::RateLimit — value object (limit, remaining as Integers; reset as a UTC Time). Blank/non-numeric header values become nil (never a misleading 0).
• RawClient gains an optional rate_limit_handler, invoked in #send after retries on every response with the parsed RateLimit. Handler errors are swallowed so a monitoring callback can never break a request. #send's return value is unchanged, so the generated callers are unaffected.
• Wiring: Auth0::Client.new(..., management_rate_limit_handler: ->(rl) { ... }) attaches the handler to the management raw client.
• All changes live in fernignored files (lib/auth0/internal/**, lib/auth0/mixins/**, lib/auth0/auth_client.rb), so they survive regeneration.
• Unit tests for RateLimit, RawClient#send handler behavior, and the client wiring.

client = Auth0::Client.new(
  domain: ENV["AUTH0_DOMAIN"],
  token: ENV["AUTH0_MGMT_TOKEN"],
  management_rate_limit_handler: lambda do |rate_limit|
    StatsD.gauge("auth0.mgmt.remaining", rate_limit.remaining) if rate_limit.remaining
  end
)
client.users.get(id: "auth0|123") # handler fires with the response's rate limit

Why a callback instead of returning the rate limit (e.g. with_raw_response)? The generated endpoint methods (Auth0::Users::Client#get, etc.) parse the body and discard the response, and they're regenerated — so a third-party change to what they return wouldn't survive. A callback invoked at the maintained RawClient layer is the part we can change durably while still delivering the data on every request. If you'd prefer to also expose it as a return value via a generated with_raw_response-style accessor, this RateLimit object slots right in — happy to align.

References

• Refs Rate limit data returned from API methods #606 (the v5 implementation, Expose Management API rate limit info via a client callback #774, is superseded by the v6 rewrite)

Testing

Unit tests under test/unit/ cover header parsing (0 vs blank/non-numeric), the handler firing with the parsed rate limit while the response is returned unchanged, handler errors not breaking the request, and the client wiring. Full rake test passes locally with no failures.

• This change adds unit test coverage
• This change adds integration test coverage
• This change has been tested on the latest version of Ruby

Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors
• Rubocop passes on all added/modified files
• All active GitHub checks have passed